home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tcl / library.man < prev    next >
Encoding:
Text File  |  1992-08-07  |  11.0 KB  |  379 lines
  1. '\"
  2. '\" Copyright 1991 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/library.man,v 1.2 91/12/06 10:35:39 ouster Exp $ SPRITE (Berkeley)
  11. '
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .de UL
  189. \\$1\l'|0\(ul'\\$2
  190. ..
  191. .HS library tcl
  192. .BS
  193. .SH NAME
  194. library \- standard library of Tcl procedures
  195. .SH SYNOPSIS
  196. .VS
  197. .nf
  198. \fBauto_execok \fIcmd\fR
  199. \fBauto_load \fIcmd\fR
  200. \fBauto_mkindex \fIdir pattern\fR
  201. \fBauto_reset\fR
  202. \fBparray \fIarrayName\fR
  203. \fBunknown \fIcmd \fR?\fIarg arg ...\fR?
  204. .fi
  205. .BE
  206.  
  207. .SH INTRODUCTION
  208. .PP
  209. Tcl includes a library of Tcl procedures for commonly-needed functions.
  210. The procedures defined in the Tcl library are generic ones suitable
  211. for use by many different applications.
  212. The location of the Tcl library is returned by the \fBinfo library\fR
  213. command.
  214. In addition to the Tcl library, each application will normally have
  215. its own library of support procedures as well;  the location of this
  216. library is normally given by the value of the \fB$appLibrary\fR
  217. global variable.
  218. .PP
  219. To access the procedures in the Tcl library, an application should
  220. source the file \fBinit.tcl\fR in the library, for example with
  221. the Tcl command
  222. .DS
  223. \fBsource [info library]/init.tcl
  224. .DE
  225. This will define the \fBunknown\fR procedure and arrange for the
  226. other procedures to be loaded on-demand using the auto-load
  227. mechanism defined below.
  228.  
  229. .SH "COMMAND PROCEDURES"
  230. .PP
  231. The following procedures are provided in the Tcl library:
  232. .TP
  233. \fBauto_execok \fIcmd\fR
  234. Determines whether there is an executable file by the name \fIcmd\fR.
  235. This command examines the directories in the current search path
  236. (given by the PATH enviornment variable) to see if there is an
  237. executable file named \fIcmd\fR in any of those directories.
  238. If so, it returns 1;  if not it returns 0.  \fBAuto_exec\fR
  239. remembers information about previous searches in an array
  240. named \fBauto_execs\fR;  this avoids the path search in
  241. future calls for the same \fIcmd\fR.  The command \fBauto_reset\fR
  242. may be used to force \fBauto_execok\fR to forget its cached
  243. information.
  244. .TP
  245. \fBauto_load \fIcmd\fR
  246. This command attempts to load the definition for a Tcl procedure named
  247. \fIcmd\fR.
  248. To do this, it searches an \fIauto-load path\fR, which is a list of
  249. one or more directories.
  250. The auto-load path is given by the global variable \fB$auto_path\fR
  251. if it exists.
  252. If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment
  253. variable is used, if it exists.
  254. Otherwise the auto-load path consists of just the Tcl library directory.
  255. Within each directory in the auto-load path there must be a file
  256. \fBtclIndex\fR that describes the procedures defined in that directory
  257. and the file in which each procedure is defined.  The \fBtclIndex\fR
  258. file should be generated with the \fBauto_mkindex\fR command.
  259. If \fIcmd\fR is found in an index file, then the appropriate
  260. script is \fBsource\fRd to create the procedure.
  261. The \fBauto_load\fR command returns 1 if the script was successfully
  262. sourced and \fIcmd\fR now exists.
  263. The command returns 0 if there was no index entry for \fIcmd\fR
  264. or if the script didn't actually define \fIcmd\fR (e.g. because
  265. index information is out of date).
  266. If an error occurs while processing the script, then that error
  267. is returned.
  268. \fBAuto_load\fR only reads the index information once and saves it
  269. in the array \fBauto_index\fR;  future calls to \fBauto_load\fR
  270. check for \fIcmd\fR in the array rather than re-reading the index
  271. files.
  272. The cached index information may be deleted with the command
  273. \fBauto_reset\fR.
  274. This will force the next \fBauto_load\fR command to reload the
  275. index database from disk.
  276. .TP
  277. \fBauto_mkindex \fIdir pattern\fR
  278. Generates an index suitable for use by \fBauto_load\fR.
  279. The command searches \fIdir\fR for all files whose names match
  280. \fIpattern\fR (matching is done with the \fBglob\fR command),
  281. generates an index of all the Tcl command
  282. procedures defined in all the matching files, and stores the
  283. index information in a file named \fBtclIndex\fR in \fIdir\fR.
  284. For example, the command
  285. .RS
  286. .DS
  287. \fBauto_mkindex foo *.tcl\fR
  288. .DE
  289. .LP
  290. will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR
  291. and generate a new index file \fBfoo/tclIndex\fR.
  292. .PP
  293. \fBAuto_mkindex\fR parses the Tcl scripts in a relatively
  294. unsophisticated way:  if any line contains the word \fBproc\fR
  295. as its first characters then it is assumed to be a procedure
  296. definition and the next word of the line is taken as the
  297. procedure's name.
  298. Procedure definitions that don't appear in this way (e.g. they
  299. have spaces before the \fBproc\fR) will not be indexed.
  300. .RE
  301. .TP
  302. \fBauto_reset\fR
  303. Destroys all the information cached by \fBauto_execok\fR and
  304. \fBauto_load\fR.
  305. This information will be re-read from disk the next time it is
  306. needed.
  307. .TP
  308. \fBparray \fIarrayName\fR
  309. Prints on standard output the names and values of all the elements
  310. in the array \fIarrayName\fR.
  311. \fBArrayName\fR must be a global array.
  312. .TP
  313. \fBunknown \fIcmd \fR?\fIarg arg ...\fR?
  314. This procedure is invoked automatically by the Tcl interpreter
  315. whenever the name of a command doesn't exist.
  316. The \fBunknown\fR procedure receives as its arguments the
  317. name and arguments of the missing command.
  318. \fBUnknown\fR first calls \fBauto_load\fR to load a procedure for
  319. the command.
  320. If this succeeds, then it executes the original command with its
  321. original arguments.
  322. If the auto-load fails then \fBunknown\fR calls \fBauto_execok\fR
  323. to see if there is an executable file by the name \fIcmd\fR.
  324. If so, it invokes the Tcl \fBexec\fR command
  325. with \fIcmd\fR and all the \fIargs\fR as arguments.
  326. If \fIcmd\fR can't be auto-executed, \fBunknown\fR checks to see if \fIcmd\fR is
  327. a unique abbreviation for an existing Tcl command.
  328. If so, it expands the command name and executes the command with
  329. the original arguments.
  330. Finally, if none of the above efforts has been able to execute
  331. the command, \fBunknown\fR generates an error return.
  332. If the global variable \fBauto_noload\fR is defined, then the auto-load
  333. step is skipped.
  334. If the global variable \fBauto_noexec\fR is defined then the
  335. auto-exec step is skipped.
  336. Under normal circumstances the return value from \fBunknown\fR
  337. is the return value from the command that was eventually
  338. executed.
  339.  
  340. .SH "VARIABLES"
  341. .PP
  342. The following global variables are defined or used by the procedures in
  343. the Tcl library:
  344. .TP
  345. \fBauto_execs\fR
  346. Used by \fBauto_execok\fR to record information about whether
  347. particular commands exist as executable files.
  348. .TP
  349. \fBauto_index\fR
  350. Used by \fBauto_load\fR to save the index information read from
  351. disk.
  352. .TP
  353. \fBauto_noexec\fR
  354. If set to any value, then \fBunknown\fR will not attempt to auto-exec
  355. any commands.
  356. .TP
  357. \fBauto_noload\fR
  358. If set to any value, then \fBunknown\fR will not attempt to auto-load
  359. any commands.
  360. .TP
  361. \fBauto_path\fR
  362. If set, then it must contain a valid Tcl list giving directories to
  363. search during auto-load operations.
  364. .TP
  365. \fBenv(TCLLIBPATH)\fR
  366. If set, then it must contain a valid Tcl list giving directories to
  367. search during auto-load operations.
  368. This variable is only used if \fBauto_path\fR is not defined.
  369. .TP
  370. \fBunknown_active\fR
  371. This variable is set by \fBunknown\fR to indicate that it is active.
  372. It is used to detect errors where \fBunknown\fR recurses on itself
  373. infinitely.
  374. The variable is unset before \fBunknown\fR returns.
  375.  
  376. .SH KEYWORDS
  377. auto-exec, auto-load, library, unknown
  378. .VE
  379.